---
title: TextRenderer 文本渲染器
icon: FileText
relatedFile: app/src/core/render/canvas2d/basicRenderer/textRenderer.tsx
---

这个服务专门用于在 Canvas 上渲染文字，并支持缓存以优化性能。它基于 View 坐标系进行操作。

该服务通过以下方式实现其功能：
- 使用 LruCache 缓存已渲染的文字位图（ImageBitmap），缓存大小由 `Settings.textCacheSize` 控制。
- 渲染文字时，优先从缓存中获取。如果缓存命中，则直接绘制缓存的位图。
- 如果缓存未命中，则使用 `OffscreenCanvas` 创建新的文字位图。选择 `OffscreenCanvas` 是因为它具有潜在的性能优化，并且方便未来移植到 Web Worker 中进行渲染。
- 在构建文字位图时，会关闭 `imageSmoothingEnabled` 以避免与外部 Canvas 的抗锯齿冲突导致文字模糊。
- 针对摄像机缩放时的文字渲染，提供了不同的策略：
  - `nearestCache`：查找大小最接近的缓存图片进行位图缩放。
  - `temp`：渲染临时文字，不使用缓存也不构建缓存。
- 内部使用 MD5 对文字内容和字体大小进行哈希，生成缓存键。
- 提供了多行文本的自动换行功能，并对换行逻辑也进行了缓存优化。

## API

### 单行文本渲染

#### `renderText(text: string, location: Vector, size: number, color: Color = Color.White): void`

从左上角位置开始绘制单行文本。
- `text`: 要渲染的文本内容。
- `location`: 文本的左上角坐标（Vector 对象）。
- `size`: 文本的字体大小。
- `color`: 文本的颜色（Color 对象），默认为白色。

#### `renderTempText(text: string, location: Vector, size: number, color: Color = Color.White): void`

渲染临时单行文本，不使用缓存也不构建缓存。
- `text`: 要渲染的文本内容。
- `location`: 文本的左上角坐标（Vector 对象）。
- `size`: 文本的字体大小。
- `color`: 文本的颜色（Color 对象），默认为白色。

#### `renderTextFromCenter(text: string, centerLocation: Vector, size: number, color: Color = Color.White): void`

从中心位置开始绘制单行文本。
- `text`: 要渲染的文本内容。
- `centerLocation`: 文本的中心坐标（Vector 对象）。
- `size`: 文本的字体大小。
- `color`: 文本的颜色（Color 对象），默认为白色。

#### `renderTempTextFromCenter(text: string, centerLocation: Vector, size: number, color: Color = Color.White): void`

从中心位置开始绘制临时单行文本，不使用缓存也不构建缓存。
- `text`: 要渲染的文本内容。
- `centerLocation`: 文本的中心坐标（Vector 对象）。
- `size`: 文本的字体大小。
- `color`: 文本的颜色（Color 对象），默认为白色。

### 多行文本渲染

#### `renderMultiLineText(text: string, location: Vector, fontSize: number, limitWidth: number, color: Color = Color.White, lineHeight: number = 1.2, limitLines: number = Infinity): void`

渲染多行文本，支持自动换行和行数限制。
- `text`: 要渲染的文本内容。
- `location`: 文本的左上角坐标（Vector 对象）。
- `fontSize`: 文本的字体大小。
- `limitWidth`: 文本的最大宽度，超出此宽度将自动换行。
- `color`: 文本的颜色（Color 对象），默认为白色。
- `lineHeight`: 行高倍数，默认为 1.2。
- `limitLines`: 最大行数限制，超出部分将显示省略号，默认为无限。

#### `renderTempMultiLineText(text: string, location: Vector, fontSize: number, limitWidth: number, color: Color = Color.White, lineHeight: number = 1.2, limitLines: number = Infinity): void`

渲染临时多行文本，不使用缓存也不构建缓存，支持自动换行和行数限制。
- `text`: 要渲染的文本内容。
- `location`: 文本的左上角坐标（Vector 对象）。
- `fontSize`: 文本的字体大小。
- `limitWidth`: 文本的最大宽度，超出此宽度将自动换行。
- `color`: 文本的颜色（Color 对象），默认为白色。
- `lineHeight`: 行高倍数，默认为 1.2。
- `limitLines`: 最大行数限制，超出部分将显示省略号，默认为无限。

#### `renderMultiLineTextFromCenter(text: string, centerLocation: Vector, size: number, limitWidth: number, color: Color, lineHeight: number = 1.2, limitLines: number = Infinity): void`

从中心位置开始绘制多行文本，支持自动换行和行数限制。
- `text`: 要渲染的文本内容。
- `centerLocation`: 文本的中心坐标（Vector 对象）。
- `size`: 文本的字体大小。
- `limitWidth`: 文本的最大宽度，超出此宽度将自动换行。
- `color`: 文本的颜色（Color 对象）。
- `lineHeight`: 行高倍数，默认为 1.2。
- `limitLines`: 最大行数限制，超出部分将显示省略号，默认为无限。

#### `renderTempMultiLineTextFromCenter(text: string, centerLocation: Vector, size: number, limitWidth: number, color: Color, lineHeight: number = 1.2, limitLines: number = Infinity): void`

从中心位置开始绘制临时多行文本，不使用缓存也不构建缓存，支持自动换行和行数限制。
- `text`: 要渲染的文本内容。
- `centerLocation`: 文本的中心坐标（Vector 对象）。
- `size`: 文本的字体大小。
- `limitWidth`: 文本的最大宽度，超出此宽度将自动换行。
- `color`: 文本的颜色（Color 对象）。
- `lineHeight`: 行高倍数，默认为 1.2。
- `limitLines`: 最大行数限制，超出部分将显示省略号，默认为无限。

### 文本测量

#### `measureMultiLineTextSize(text: string, fontSize: number, limitWidth: number, lineHeight: number = 1.2): Vector`

测量多行文本在给定字体大小、限制宽度和行高下的总尺寸。
- `text`: 要测量的文本内容。
- `fontSize`: 文本的字体大小。
- `limitWidth`: 文本的最大宽度。
- `lineHeight`: 行高倍数，默认为 1.2。
- 返回值: 一个 Vector 对象，表示文本的总宽度和总高度。
